/************************************************************************
  Copyright    : 2005-2007, Huawei Tech. Co., Ltd.
  File name    : HiPM_queue.h
  Author       : y60469
  Version      : V100R001
  Date         : 2007-04-20
  Description  :
      this file declare the message queue ecapsulation .
  Function List:
      HiPM_OpenQueue           //OpenMsgQueue
      HiPM_CreateQueue         //CreateMsgQueue
      HiPM_CreateReadQueue  //Create a readonly Queue
      HiPM_CreateWriteQueue //Create a Write-only queue.
      HiPM_CloseMsgQueue     //close the msg queue handle.
      HiPM_GetQueueInfo       //GetMsgQueueInfo
      HiPM_WriteMsgQueue    //ReadMsgQueue
      HiPM_ReadMsgQueue     //WriteMsgQueue
  History      :
  1. Date:2007-04.20
     Author: y60469
     Modification:create the file.
************************************************************************/

#pragma once

#include <windows.h>
#include "Msgqueue.h"
#include "HiPM_Common.h"

#define QUEUE_TIME_OUT 10          //message queue transition wait for 10 ms
#define HiPM_READ_QUEUE TRUE       //read flag
#define HiPM_WRITE_QUEUE FALSE     //write flag


#ifdef __cplusplus
extern "C"{
#endif
/***********************************
Function: HiPM_OpenQueue
Description: open a queue
Calls:
Called by:
Table Access:
Table Update:
Input:      bReadAccess  Set to TRUE to request read access to the queue
            hMsgQ        Event handle to a message queue returned by the CreateMsgQueue function
            hSrcProc     Handle to a source process that owns the hMsgQ message queue handle
Output:
Return:     Returns a handle to a message queue, or returns NULL if the queue
            could not be opened
Others:
***********************************/
HANDLE HiPM_OpenQueue(BOOL bReadAccess,
                                HANDLE hMsgQ,
                                HANDLE hSrcProc);

/***********************************
Function: HiPM_CreateQueue
Description: create a queue
Calls:
Called by:
Table Access:
Table Update:
Input:      bReadAccess          Set to TRUE to request read access to the queue
            szQueueName          Name of the message queue
            dwMaxMsgByteSize    Maximum number of bytes in each message
            dwMaxMsgsInQ           Maximum number of messages to queue at any one time
Output:
Return:     If the function succeeds, the return value is a read-only or write-only handle
            to the specified queue. If a read-only handle is returned, the queue signals when
            data is put into the queue. The signal is reset in the ReadMsgQueue function.
Others:
***********************************/
HANDLE HiPM_CreateQueue(BOOL bReadAccess,
                                LPCWSTR szQueueName,
                                DWORD dwMaxMsgByteSize,
                                DWORD dwMaxMsgsInQ)    ;

/***********************************
Function: HiPM_CreateReadQueue
Description: create a read queue
Calls:
Called by:
Table Access:
Table Update:
Input:
            szQueueName          Name of the message queue
            dwMaxMsgByteSize    Maximum number of bytes in each message
            dwMaxMsgsInQ           Maximum number of messages to queue at any one time
Output:
Return:     If the function succeeds, the return value is a read-only or write-only handle
            to the specified queue. If a read-only handle is returned, the queue signals when
            data is put into the queue. The signal is reset in the ReadMsgQueue function.


Others:
***********************************/
const HANDLE HiPM_CreateReadQueue(LPCWSTR szQueueName,
                                            DWORD dwMaxMsgByteSize,
                                            DWORD dwMaxMsgsInQ);

/***********************************
Function: HiPM_CreateWriteQueue
Description: create a write queue
Calls:
Called by:
Table Access:
Table Update:
Input:
            szQueueName          Name of the message queue
            dwMaxMsgByteSize    Maximum number of bytes in each message
            dwMaxMsgsInQ           Maximum number of messages to queue at any one time
Output:
Return:     If the function succeeds, the return value is a read-only or write-only handle
            to the specified queue. If a read-only handle is returned, the queue signals when
            data is put into the queue. The signal is reset in the ReadMsgQueue function.


Others:
***********************************/
const HANDLE HiPM_CreateWriteQueue(LPCWSTR szQueueName,
                                            DWORD dwMaxMsgByteSize,
                                            DWORD dwMaxMsgsInQ);

/***********************************
Function: HiPM_CloseMsgQueue
Description: close a queue
Calls:
Called by:
Table Access:
Table Update:
Input:
            hQueue          handle of the message queue
Output:
Return:     Returns TRUE if the close succeeds; otherwise, returns FALSE
Others:
***********************************/
STATUS_CODE HiPM_CloseMsgQueue(HANDLE hQueue);

/***********************************
Function: HiPM_GetQueueInfo
Description: get a queue's info
Calls:
Called by:
Table Access:
Table Update:
Input:
            hQueue[in]              handle of the message queue
            lpMsgQueueInfo[out]        Pointer to an MSGQUEUEINFO structure that returns
                                    information about the message queue.
Output:
Return:     Returns TRUE if the close succeeds; otherwise, returns FALSE
Others:
***********************************/
STATUS_CODE HiPM_GetQueueInfo(HANDLE hQueue,LPMSGQUEUEINFO lpMsgQueueInfo);

/***********************************
Function: HiPM_WriteMsgQueue
Description: write msg to a queue
Calls:
Called by:
Table Access:
Table Update:
Input:      hQueue                handle of the message queue
            lpBuffer              Pointer to a buffer that contains data to write to a message queue
            cbDataSize          Number of bytes stored in lpBuffer that comprise a message

Output:
Return:     Returns TRUE if the write operation succeeds; otherwise, returns FALSE
Others:
***********************************/
STATUS_CODE HiPM_WriteMsgQueue(HANDLE hQueue,LPVOID lpBuffer,DWORD cbDataSize);


/***********************************
Function: HiPM_ReadMsgQueue
Description: write msg to a queue
Calls:
Called by:
Table Access:
Table Update:
Input:      hQueue[in]                handle of the message queue
            lpBuffer[out]              Pointer to a buffer to store a read message.
            cbBufferSize[in]          Size of the buffer, in bytes, specified by lpBuffer.

Output:
Return:     Returns TRUE if the write operation succeeds; otherwise, returns FALSE
Others:
***********************************/
STATUS_CODE HiPM_ReadMsgQueue(HANDLE hQueue,LPVOID lpBuffer,DWORD cbBufferSize,DWORD timeout);


#ifdef __cplusplus
}
#endif


